health`

Endpoint: GET /api/health
Auth Scope: Public Loopback (No secret required)
Target Service: Local DaemonX Bridge Daemon (127.0.0.1:9123)
Introduced In: v1.0.0
Last Updated: v1.0.0

1. Description & Purpose

GET /api/health is an ultra-fast, unauthenticated liveness and readiness probe for the DaemonX Windows desktop bridge.

Web POS applications call this endpoint to verify:

Is the DaemonX background service running on the workstation?
Is the current counter paired and ready to print?

Wiring this endpoint into any frontend takes less than 5 minutes.

2. Request Contract

Header	Type	Required	Description
`Accept`	`string`	No	`application/json`

Query Parameters

Parameter	Type	Required	Description
`counter_id`	`string` (UUID)	Optional	The specific counter profile to query. If omitted, DaemonX returns the currently active profile on the machine.

3. TypeScript Contract

export interface DaemonXHealthResponse {
  status: 'ok';
  online: boolean;
  app: string;
  version: string;
  port: number;
  counter_id: string | null;
  counter_name: string | null;
  counter_status: 'active' | 'not_paired' | 'disabled';
  is_paired: boolean;
  business_verified: boolean;
}

4. Response Field Matrix

Field	Type	Description
`status`	`string`	Always `"ok"` if daemon is running.
`online`	`boolean`	`true` when the local DaemonX daemon handled the loopback request. This is a daemon liveness flag, not the Core heartbeat/offline allowance state.
`app`	`string`	Always `"DaemonX"`.
`version`	`string`	Installed desktop version (e.g. `"1.0.2"`).
`port`	`number`	Active HTTP port (defaults to `9123`).
`counter_id`	`string \| null`	UUID of the resolved counter profile.
`counter_name`	`string \| null`	Human-readable counter name (e.g. `"Counter 1"`).
`counter_status`	`string`	`"active"` when paired and usable, `"not_paired"`, or `"disabled"`.
`is_paired`	`boolean`	`true` if local workstation is paired and ready.
`business_verified`	`boolean`	`true` if the merchant's business entity is verified.

5. Real-World Response Examples

Example A: Paired Counter (200 OK)

{
  "status": "ok",
  "online": true,
  "app": "DaemonX",
  "version": "1.0.2",
  "port": 9123,
  "counter_id": "d402ddec-ecf7-4b39-b57a-86ce6008df05",
  "counter_name": "Counter 1",
  "counter_status": "active",
  "is_paired": true,
  "business_verified": true
}

Example B: Workstation Installed, Not Yet Paired (200 OK)

{
  "status": "ok",
  "online": true,
  "app": "DaemonX",
  "version": "1.0.2",
  "port": 9123,
  "counter_id": null,
  "counter_name": null,
  "counter_status": "not_paired",
  "is_paired": false,
  "business_verified": false
}

6. Integration Snippets

cURL

curl -X GET "http://127.0.0.1:9123/api/health" \
  -H "Accept: application/json"

TypeScript Client Function

export async function checkDaemonXHealth(
  counterId?: string
): Promise<DaemonXHealthResponse | null> {
  const url = counterId 
    ? `http://127.0.0.1:9123/api/health?counter_id=${encodeURIComponent(counterId)}`
    : 'http://127.0.0.1:9123/api/health';

  try {
    const res = await fetch(url, {
      method: 'GET',
      headers: { 'Accept': 'application/json' },
      signal: AbortSignal.timeout(2000), // 2s timeout
    });

    if (!res.ok) return null;
    return (await res.json()) as DaemonXHealthResponse;
  } catch {
    // DaemonX is not running on this host
    return null;
  }
}

POS UI Indicator Example

function getHardwareBridgeBadge(health: DaemonXHealthResponse | null) {
  if (!health) {
    return { status: 'DISCONNECTED', label: 'DaemonX Not Running', color: 'red' };
  }
  if (!health.is_paired) {
    return { status: 'UNPAIRED', label: 'Counter Not Paired', color: 'gray' };
  }
  return { status: 'READY', label: `Connected (${health.counter_name})`, color: 'emerald' };
}

Health Check